Problem

An agent with a skill whose loadable name differs from its internal ## Tool: heading could never load that skill. Observed live: the LLM was shown k8s_triage in the skill catalog and called read_skill{"name":"k8s_triage"}, but the skill's loadable name (frontmatter name / directory, also what the agent card advertises) was k8s-incident-triage. read_skill resolves by filesystem path, so it returned {"error":"skill \"k8s_triage\" not found"}, and the model abandoned the skill and improvised raw kubectl.

Root cause: three divergent identifiers for one skill.

The catalog advertised the internal tool heading while read_skill resolved by the skill's loadable name, and the two never had to agree. Unit tests never crossed the catalog→read_skill boundary, so nothing caught it.

Changes

buildSkillCatalog (forge-cli/runtime/runner.go) — now emits one line per skill keyed by the loadable name (frontmatter name, falling back to directory/file) — the exact string read_skill resolves and the agent card advertises. Each line also carries a provides: <tool names> list so the LLM still sees the skill's capabilities for tool selection, without mistaking them for the read_skill argument. Script/binary-backed ## Tool: entries are excluded from provides because they are registered as first-class callable tools (registerSkillTools) and invoked directly by name.

## Available Skills

To use a skill, call `read_skill` with the skill name (the identifier before the colon)
to load its full instructions, then follow them. `provides:` lists the capabilities inside
a skill — they are documentation loaded with the skill, not tools you call directly.

- k8s-incident-triage: Read-only Kubernetes incident triage using kubectl. [provides: k8s_triage] (uses cli_execute)

read_skill (forge-core/tools/builtins/read_skill.go) — resolves via a frontmatter-name index (keyed by both the frontmatter name and the directory/file name, normalized for case and _/- drift) in addition to the direct path lookup. A miss now returns the available skill names (available_skills) so the model can retry instead of giving up. Directory-traversal guard preserved.

Why both halves

• The catalog fix makes the model call read_skill with the resolvable name in the common case (directory == frontmatter name).
• The read_skill index makes resolution robust when the directory differs from the frontmatter name, and turns a dead-end "not found" into an actionable list.

Tests

• forge-core/tools/builtins/read_skill_test.go — resolves by frontmatter name when the directory differs; normalized variants (k8s_incident_triage, K8S-Incident-Triage); flat skills/<name>.md layout; not-found lists available skills; traversal rejected.
• forge-cli/runtime/runner_skill_catalog_test.go — catalog keys the line on the loadable name (not the tool heading) while surfacing tool names under provides; and a catalog↔read_skill contract test asserting every advertised name resolves through read_skill (the integration gap that let this ship).

Full forge-core/tools/... and forge-cli/runtime suites green; gofmt -w + golangci-lint run clean on both changed packages.